Summary

Stacked on #95 (→ #94 → #93 → #92 → #91). Reference document for AI agents and CI systems driving deno deploy without a human at the terminal.

Complements per-command --help by capturing the conventions that span every subcommand and that aren't obvious without reading the source.

What's in this PR

• Token authentication — env var, `--token`, keychain priority; the "never opens a browser" guarantee when a token is supplied explicitly.
• Global flag set — `--json`, `--non-interactive` (and its `-y`/`--yes` aliases), `--quiet`, `--debug`, `--endpoint`, `--token`, `--config`.
• Exit-code taxonomy — the OK=0, GENERIC=1, USAGE=2, AUTH=3, NOT_FOUND=4, CONFLICT=5, NETWORK=6 table from feat: add --json, --non-interactive flags and exit-code taxonomy #91, with the convention that agents check the code before parsing stderr.
• Structured error envelope — the `{ error: { code, message, hint, traceId } }` shape.
• JSON output schemas — one section per command that already emits JSON: `whoami`, `orgs list`, `apps list`, `deployments list`, `env list`, `database list`/`query`, `publish`, `create` (--dry-run and github source), and the NDJSON shape for `logs`.
• Non-interactive flag coverage matrix — required flags per subcommand under `--non-interactive`.
• Stdio discipline rules — what lands on stdout vs stderr.
• Five copy-pasteable example flows — auth check, create + publish, re-deploy to existing app, env load, pagination, AWS setup.

Test plan

• `deno fmt` clean (`AGENTS.md` is fmt-managed).
• Schemas verified against the actual `--json` payloads emitted by the implementations in feat: add --json, --non-interactive flags and exit-code taxonomy #91-feat: add deno deploy whoami and conflict hint #95.
• Example commands verified to parse and reach the relevant code path (with a localhost endpoint to confirm the auth flow).
• Reads top-to-bottom as a single document; the structure mirrors what an agent needs in order: auth → flags → exit codes → errors → schemas → flag coverage → examples.

🤖 Generated with Claude Code